<!DOCTYPE html>
<html>
  <head>
    <title>Development</title>
  </head>
  <body>

<h1>Intel&reg; x86 coreboot/FSP Development Process</h1>
<p>
  The x86 development process for coreboot is broken into the following components:
</p>
<ul>
  <li>coreboot <a target="_blank" href="SoC/soc.html">SoC</a> development</li>
  <li>coreboot <a target="_blank" href="Board/board.html">mainboard</a> development</li>
  <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration</li>
</ul>
<p>
  The development process has two main phases:
</p>
<ol>
  <li>Minimal coreboot; This phase is single threaded</li>
  <li>Adding coreboot features</li>
</ol>

<h2>Minimal coreboot</h2>
<p>
  The combined steps below describe how to bring up a minimal coreboot for a
  system-on-a-chip (SoC) and a development board:
</p>
<table>
  <tr bgcolor="#ffffc0">
    <td>The initial coreboot steps are single threaded!
      The initial minimal FSP development is also single threaded.
      Progress can speed up by adding more developers after the minimal coreboot/FSP
      implementation reaches the payload.
    </td>
  </tr>
</table>
<ol>
  <li>Get the necessary tools:
    <ul>
      <li>Linux: Use your package manager to install m4 bison flex and the libcurses development
        package.
        <ul>
          <li>Ubuntu or other Linux distribution that use apt, run:
<pre><code>sudo apt-get install m4 bison flex libncurses5-dev
</code></pre>
          </li>
        </ul>
      </li>
    </ul>
  </li>
  <li>Build the cross tools for i386:
    <ul>
      <li>Linux:
<pre><code>make crossgcc-i386</code></pre>
        To use multiple processors for the toolchain build (which takes a long time), use:
<pre><code>make crossgcc-i386 CPUS=N</code></pre>
        where N is the number of cores to use for the build.
      </li>
    </ul>
  </li>
  <li>Get something to build:
    <ol type="A">
      <li><a target="_blank" href="fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
      <li><a target="_blank" href="SoC/soc.html#RequiredFiles">SoC</a> required files</li>
      <li><a target="_blank" href="Board/board.html#RequiredFiles">Board</a> required files</li>
    </ol>
  </li>
  <li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li>
  <li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li>
  <li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li>
  <li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li>
  <li>Enable the serial port
    <ol type="A">
      <li>Power on, enable and configure GPIOs for the
        <a target="_blank" href="Board/board.html#SerialOutput">debug serial UART</a>
      </li>
      <li>Add the <a target="_blank" href="SoC/soc.html#SerialOutput">serial outupt</a>
        support to romstage
      </li>
    </ol>
  </li>
  <li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li>
  <li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li>
  <li>Enable DRAM:
    <ol type="A">
      <li>Implement the SoC
        <a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a>
        Support
      </li>
      <li>Implement the board support to read the
        <a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a>
      </li>
    </ol>
  </li>
  <li>Disable the
    <a target="_blank" href="SoC/soc.html#DisableShadowRom">Shadow ROM</a>
  </li>
  <li>Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration</li>
  <li>
    Implement the .init routine for the
    <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a>
    structure which calls FSP SiliconInit
  </li>
  <li>
    Start ramstage's
    <a target="_blank" href="SoC/soc.html#DeviceTree">device tree processing</a>
    to display the PCI vendor and device IDs
  </li>
  <li>
    Disable the
    <a target="_blank" href="Board/board.html#DisablePciDevices">PCI devices</a>
  </li>
  <li>
    Implement the
    <a target="_blank" href="SoC/soc.html#MemoryMap">memory map</a>
  </li>
  <li>coreboot should now attempt to load the payload</li>
</ol>



<h2>Add coreboot Features</h2>
<p>
  Most of the coreboot development gets done in this phase.  Implementation tasks in this
  phase are easily done in parallel.
</p>
<ul>
  <li>Payload and OS Features:
    <ul>
      <li><a target="_blank" href="SoC/soc.html#AcpiTables">ACPI Tables</a></li>
      <li><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</li>
    </ul>
  </li>
</ul>



<hr>
<table border="1">
  <tr bgcolor="#c0ffc0">
    <th colspan=3><h1>Features</h1></th>
  </tr>
  <tr bgcolor="#c0ffc0">
    <th>SoC</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>8254 Programmable Interval Timer</td>
    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
  </tr>
  <tr>
    <td>8259 Programmable Interrupt Controller</td>
    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
  </tr>
  <tr>
    <td>Cache-as-RAM</td>
    <td>
      <a target="_blank" href="SoC/soc.html#TempRamInit">Find</a>
      FSP binary:
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l38">cache_as_ram.inc</a><br>
      Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a>
      called from
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">cache_as_ram.inc</a><br>
      Disable: FSP 1.1 TempRamExit called from
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
    </td>
    <td>FindFSP: POST code 0x90
      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
      is displayed<br>
      Enable: POST code
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
      is displayed<br>
      Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit
    </td>
  </tr>
  <tr>
    <td>Memory Map</td>
    <td>
      Implement a device driver for the
      <a target="_blank" href="SoC/soc.html#MemoryMap">north cluster</a>
    </td>
    <td>coreboot displays the memory map correctly during the BS_WRITE_TABLES state</td>
  </tr>
  <tr>
    <td>MTRRs</td>
    <td>
      Set values: src/drivers/intel/fsp1_1/stack.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/stack.c;hb=HEAD#l42">setup_stack_and_mtrrs</a><br>
      Load values: src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l71">after_raminit.S</a>
    </td>
    <td>Set: Post code 0x91
      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l213">POST_FSP_TEMP_RAM_EXIT</a>)
      is displayed by
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
      Load: Post code 0x3C is displayed by
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l152">after_raminit.S</a><br>
      and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions</td>
  </tr>
  <tr>
    <td>PCI Device Support</td>
    <td>Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a></td>
    <td>The device is detected by coreboot and usable by the payload</td>
  </tr>
  <tr>
    <td>Ramstage state machine</td>
    <td>
      Implement the chip and domain operations to start the
      <a target="_blank" href="SoC/soc.html#DeviceTree">device tree</a>
      processing
    </td>
    <td>
      During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
      for the PCI devices on the bus.
    </td>
  </tr>
  <tr>
    <td>ROM Shadow<br>0x000E0000 - 0x000FFFFF</td>
    <td>
      Disable: src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/romstage/romstage.c/<a target="_blank" href="SoC/soc.html#DisableShadowRom">soc_after_ram_init routine</a>
    </td>
    <td>Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written</td>
  </tr>


  <tr bgcolor="#c0ffc0">
    <th>Board</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>Device Tree</td>
    <td>
      <a target="_blank" href="SoC/soc.html#DeviceTree">List</a> PCI vendor and device IDs by starting
      the device tree processing<br>
      <a target="_blank" href="Board/board.html#DisablePciDevices">Disable</a> PCI devices<br>
      Enable: Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a>
    <td>
      List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs<br>
      Disable: BS_DEV_ENUMERATE state shows the devices as disabled<br>
      Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload
    </td>
  </tr>
  <tr>
    <td>DRAM</td>
    <td>
      Load SPD data: src/soc/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/spd/<a target="_blank" href="Board/board.html#SpdData">spd.c</a><br>
      UPD Setup:
      <ul>
        <li>src/soc&lt;Vendor&gt;//&lt;Chip Family&gt;/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li>
        <li>src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li>
      </ul>
      FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l126">raminit.c</a>
    </td>
    <td>Select the following Kconfig values
      <ul>
        <li>DISPLAY_HOBS</li>
        <li>DISPLAY_UPD_DATA</li>
      </ul>
      Testing successful if:
      <ul>
        <li>MemoryInit UPD values are correct</li>
        <li>MemoryInit returns 0 (success) and</li>
        <li>The message "ERROR - coreboot's requirements not met by FSP binary!"
          is not displayed
        </li>
      </ul>
    </td>
  </tr>
  <tr>
    <td>Serial Port</td>
    <td>
      SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br>
      Enable: src/soc/mainboard/&lt;Board&gt;/com_init.c/<a target="_blank" href="Board/board.html#SerialOutput">car_mainboard_pre_console_init</a>
    </td>
    <td>Debug serial output works</td>
  </tr>


  <tr bgcolor="#c0ffc0">
    <th>Payload</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>ACPI Tables</td>
    <td>
      SoC <a target="_blank" href="SoC/soc.html#AcpiTables">Support</a><br>
    </td>
    <td>Verified by payload or OS</td>
  </tr>


  <tr bgcolor="#c0ffc0">
    <th>FSP</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>TempRamInit</td>
    <td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td>
    <td>FSP binary found: POST code 0x90
      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
      is displayed<br>
      TempRamInit successful: POST code
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
      is displayed<br>
    </td>
  </tr>
  <tr>
    <td>MemoryInit</td>
    <td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br>
      <a target="_blank" href="Board/board.html#SpdData">Board</a> support<br>
    </td>
    <td>Select the following Kconfig values
      <ul>
        <li>DISPLAY_HOBS</li>
        <li>DISPLAY_UPD_DATA</li>
      </ul>
      Testing successful if:
      <ul>
        <li>MemoryInit UPD values are correct</li>
        <li>MemoryInit returns 0 (success) and</li>
        <li>The message "ERROR - coreboot's requirements not met by FSP binary!"
          is not displayed
        </li>
      </ul>
    </td>
  </tr>
  <tr>
    <td>TempRamExit</td>
    <td>src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l51">after_raminit.S</a></td>
    <td>Post code 0x91
      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l212">POST_FSP_TEMP_RAM_EXIT</a>)
      is displayed before calling TempRamExit by
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a>,
      CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and
      Post code 0x39 is displayed by
      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a><br>
    </td>
  </tr>
  <tr>
    <td>SiliconInit</td>
    <td>
      Implement the .init routine for the
      <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> structure
    </td>
    <td>During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000</td>
  </tr>
  <tr>
    <td>FspNotify</td>
    <td>
      The code which calls FspNotify is located in
      src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/fsp_util.c;hb=HEAD#l182">fsp_util.c</a>.
      The fsp_notify_boot_state_callback routine is called three times as specified
      by the BOOT_STATE_INIT_ENTRY macros below the routine.
    </td>
    <td>
      The FspNotify routines are called during:
      <ul>
        <li>BS_DEV_RESOURCES - on exit</li>
        <li>BS_PAYLOAD_LOAD - on exit</li>
        <li>BS_OS_RESUME - on entry (S3 resume)</li>
      </ul>
    </td>
  </tr>
</table>



<hr>
<p>Modified: 4 March 2016</p>
  </body>
</html>
